// 《围棋》作者版权所有。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

package types2

import (
	"cmd/compile/internal/syntax"
)

// 标签检查身体是否正确使用标签。
func (check *Checker) labels(body *syntax.BlockStmt) {
	// 此正文中所有标签的集合
	all := NewScope(nil, body.Pos(), syntax.EndPos(body), "label")

	fwdJumps := check.blockBranches(all, nil, nil, body.List)

	// 如果还有任何向前跳转，则找不到
	// 相应goto语句的标签。这些标签要么是
	// 从未定义，要么是在块内，无法访问相应GOTO的
	// 标签。
	for _, jmp := range fwdJumps {
		var msg string
		name := jmp.Label.Value
		if alt := all.Lookup(name); alt != nil {
			msg = "goto %s jumps into block"
			alt.(*Label).used = true // 避免另一个错误
		} else {
			msg = "label %s not declared"
		}
		check.errorf(jmp.Label, msg, name)
	}

	// 说明：“定义从未使用过的标签是非法的。”
	for name, obj := range all.elems {
		obj = resolve(name, obj)
		if lbl := obj.(*Label); !lbl.used {
			check.softErrorf(lbl.pos, "label %s declared but not used", lbl.name)
		}
	}
}

// 块跟踪块及其封闭块中的标签声明。
type block struct {
	parent *block                         // 封闭块
	lstmt  *syntax.LabeledStmt            // 此块所属的带标签语句，或nil 
	labels map[string]*syntax.LabeledStmt // 延迟分配
}

// insert为当前块记录一个新的标签声明。
// 标签之前不得在任何区块中声明。
func (b *block) insert(s *syntax.LabeledStmt) {
	name := s.Label.Value
	if debug {
		assert(b.gotoTarget(name) == nil)
	}
	labels := b.labels
	if labels == nil {
		labels = make(map[string]*syntax.LabeledStmt)
		b.labels = labels
	}
	labels[name] = s
}

// gotoTarget返回当前
// 中带标签的语句，或具有给定标签名的封闭块，或nil。
func (b *block) gotoTarget(name string) *syntax.LabeledStmt {
	for s := b; s != nil; s = s.parent {
		if t := s.labels[name]; t != nil {
			return t
		}
	}
	return nil
}

// enclosuringTarget返回最里面的带标签的
// 语句，该语句具有给定的标签名，或为零。
func (b *block) enclosingTarget(name string) *syntax.LabeledStmt {
	for s := b; s != nil; s = s.parent {
		if t := s.lstmt; t != nil && t.Label.Value == name {
			return t
		}
	}
	return nil
}

// BlockBranchs处理块的语句列表并返回传出向前跳转的集合。
// all是所有已声明标签的作用域，是紧随其后的
// 封闭块中声明的标签集的父级，lstmt是与该块关联的已标记语句（或nil）。
func (check *Checker) blockBranches(all *Scope, parent *block, lstmt *syntax.LabeledStmt, list []syntax.Stmt) []*syntax.BranchStmt {
	b := &block{parent, lstmt, nil}

	var (
		varDeclPos         syntax.Pos
		fwdJumps, badJumps []*syntax.BranchStmt
	)

	// 跳过变量声明的所有向前跳转可能都是无效的（它们仍然可能跳出块并正常）。
	// recordVarDecl为给定职位记录它们。
	recordVarDecl := func(pos syntax.Pos) {
		varDeclPos = pos
		badJumps = append(badJumps[:0], fwdJumps...) // 将FWD跳转复制到坏跳转
	}

	jumpsOverVarDecl := func(jmp *syntax.BranchStmt) bool {
		if varDeclPos.IsKnown() {
			for _, bad := range badJumps {
				if jmp == bad {
					return true
				}
			}
		}
		return false
	}

	var stmtBranches func(syntax.Stmt)
	stmtBranches = func(s syntax.Stmt) {
		switch s := s.(type) {
		case *syntax.DeclStmt:
			for _, d := range s.DeclList {
				if d, _ := d.(*syntax.VarDecl); d != nil {
					recordVarDecl(d.Pos())
				}
			}

		case *syntax.LabeledStmt:
			// 声明非空标签
			if name := s.Label.Value; name != "_" {
				lbl := NewLabel(s.Label.Pos(), check.pkg, name)
				if alt := all.Insert(lbl); alt != nil {
					var err error_
					err.soft = true
					err.errorf(lbl.pos, "label %s already declared", name)
					err.recordAltDecl(alt)
					check.report(&err)
					// 继续
				} else {
					b.insert(s)
					check.recordDef(s.Label, lbl)
				}
				// 解决匹配的向前跳转并将其从FWD跳转中删除
				i := 0
				for _, jmp := range fwdJumps {
					if jmp.Label.Value == name {
						// 匹配
						lbl.used = true
						check.recordUse(jmp.Label, lbl)
						if jumpsOverVarDecl(jmp) {
							check.softErrorf(
								jmp.Label,
								"goto %s jumps over variable declaration at line %d",
								name,
								varDeclPos.Line(),
							)
							// 继续
						}
					} else {
						// 不匹配-记录新的向前跳转
						fwdJumps[i] = jmp
						i++
					}
				}
				fwdJumps = fwdJumps[:i]
				lstmt = s
			}
			stmtBranches(s.Stmt)

		case *syntax.BranchStmt:
			if s.Label == nil {
				return // 第一次通过检查（check.stmt）
			}

			// 确定并验证目标
			name := s.Label.Value
			switch s.Tok {
			case syntax.Break:
				// 规范：“如果有标签，它必须是一个封装的
				// “for”、“switch”或“select”语句的标签，这是一个
				// 其执行终止。”
				valid := false
				if t := b.enclosingTarget(name); t != nil {
					switch t.Stmt.(type) {
					case *syntax.SwitchStmt, *syntax.SelectStmt, *syntax.ForStmt:
						valid = true
					}
				}
				if !valid {
					check.errorf(s.Label, "invalid break label %s", name)
					return
				}

			case syntax.Continue:
				// spec:“如果有标签，它必须是一个封装的
				// ”的“语句，这是一个执行进展的语句。”
				valid := false
				if t := b.enclosingTarget(name); t != nil {
					switch t.Stmt.(type) {
					case *syntax.ForStmt:
						valid = true
					}
				}
				if !valid {
					check.errorf(s.Label, "invalid continue label %s", name)
					return
				}

			case syntax.Goto:
				if b.gotoTarget(name) == nil {
					// 标签可能稍后声明-将分支添加到正向跳转
					fwdJumps = append(fwdJumps, s)
					return
				}

			default:
				check.errorf(s, invalidAST+"branch statement: %s %s", s.Tok, name)
				return
			}

			// 记录标签使用
			obj := all.Lookup(name)
			obj.(*Label).used = true
			check.recordUse(s.Label, obj)

		case *syntax.AssignStmt:
			if s.Op == syntax.Def {
				recordVarDecl(s.Pos())
			}

		case *syntax.BlockStmt:
			// 嵌套块内未解析的正向跳转
			// 成为当前块中的正向跳转。
			fwdJumps = append(fwdJumps, check.blockBranches(all, b, lstmt, s.List)...)

		case *syntax.IfStmt:
			stmtBranches(s.Then)
			if s.Else != nil {
				stmtBranches(s.Else)
			}

		case *syntax.SwitchStmt:
			b := &block{b, lstmt, nil}
			for _, s := range s.Body {
				fwdJumps = append(fwdJumps, check.blockBranches(all, b, nil, s.Body)...)
			}

		case *syntax.SelectStmt:
			b := &block{b, lstmt, nil}
			for _, s := range s.Body {
				fwdJumps = append(fwdJumps, check.blockBranches(all, b, nil, s.Body)...)
			}

		case *syntax.ForStmt:
			stmtBranches(s.Body)
		}
	}

	for _, s := range list {
		stmtBranches(s)
	}

	return fwdJumps
}
